<template><div><p>本文档最新版为 <a href="https://learnku.com/docs/laravel/10.x" target="_blank" rel="noopener noreferrer">10.x</a>，旧版本可能放弃维护，推荐阅读最新版！</p>
<h2 id="laravel-sail" tabindex="-1"><a class="header-anchor" href="#laravel-sail"><span>Laravel Sail</span></a></h2>
<ul>
<li><a href="#introduction">介绍</a></li>
<li><a href="#installation">安装和设置</a>
<ul>
<li><a href="#installing-sail-into-existing-applications">将 Sail 安装到现有应用程序中</a></li>
<li><a href="#rebuilding-sail-images">重建 Sail 镜像</a></li>
<li><a href="#configuring-a-shell-alias">配置 Shell 别名</a></li>
</ul>
</li>
<li><a href="#starting-and-stopping-sail">启动和停止 Sail</a></li>
<li><a href="#executing-sail-commands">执行命令</a>
<ul>
<li><a href="#executing-php-commands">执行 PHP 命令</a></li>
<li><a href="#executing-composer-commands">执行 Composer 命令</a></li>
<li><a href="#executing-artisan-commands">执行 Artisan 命令</a></li>
<li><a href="#executing-node-npm-commands">执行 Node / NPM 命令</a></li>
</ul>
</li>
<li><a href="#interacting-with-sail-databases">与数据库交互</a>
<ul>
<li><a href="#mysql">MySQL</a></li>
<li><a href="#redis">Redis</a></li>
<li><a href="#meilisearch">Meilisearch</a></li>
<li><a href="#typesense">Typesense</a></li>
</ul>
</li>
<li><a href="#file-storage">文件存储</a></li>
<li><a href="#running-tests">运行测试</a>
<ul>
<li><a href="#laravel-dusk">Laravel Dusk</a></li>
</ul>
</li>
<li><a href="#previewing-emails">预览电子邮件</a></li>
<li><a href="#sail-container-cli">容器 CLI</a></li>
<li><a href="#sail-php-versions">PHP 版本</a></li>
<li><a href="#sail-node-versions">Node 版本</a></li>
<li><a href="#sharing-your-site">共享您的网站</a></li>
<li><a href="#debugging-with-xdebug">使用 Xdebug 进行调试</a>
<ul>
<li><a href="#xdebug-cli-usage">通过命令行使用 Xdebug 进行调试</a></li>
<li><a href="#xdebug-browser-usage">通过浏览器使用 Xdebug 进行调试</a></li>
</ul>
</li>
<li><a href="#sail-customization">定制化</a></li>
</ul>
<h2 id="介绍" tabindex="-1"><a class="header-anchor" href="#介绍"><span>介绍</span></a></h2>
<p><a href="https://github.com/laravel/sail" target="_blank" rel="noopener noreferrer">Laravel Sail</a> 是一个轻量级的命令行界面，用于与 Laravel 的默认 Docker 开发环境进行交互。Sail 为使用 PHP, MySQL, 和 Redis 构建 Laravel 应用提供了一个很好的起点，而不需要事先有 Docker 经验。</p>
<p>从本质上讲，Sail 是存储在项目根目录中的 <code v-pre>docker-compose.yml</code> 文件和 <code v-pre>sail</code> 脚本。该 <code v-pre>sail</code> 脚本提供了一个 CLI，其中包含与 <code v-pre>docker-compose.yml</code> 文件定义的 Docker 容器进行交互的便捷方法。</p>
<p>Laravel Sail 支持 macOS、Linux 和 Windows （通过 <a href="https://docs.microsoft.com/en-us/windows/wsl/about" target="_blank" rel="noopener noreferrer">WSL2</a>）。</p>
<h2 id="安装和设置" tabindex="-1"><a class="header-anchor" href="#安装和设置"><span>安装和设置</span></a></h2>
<p>Laravel Sail 会随着所有全新的 Laravel 应用程序一起自动安装，因此你可以立即的开始使用它。要了解如何创建一个新的 Laravel 应用程序，请查阅适合您目前操作系统的 <a href="https://learnku.com/docs/laravel/11.x/installation#docker-installation-using-sail" target="_blank" rel="noopener noreferrer">安装文档</a>。在安装过程中，你将被要求选择你的应用程序将与哪些 Sail 支持的服务进行交互。</p>
<h3 id="将-sail-安装到现有应用程序中" tabindex="-1"><a class="header-anchor" href="#将-sail-安装到现有应用程序中"><span>将 Sail 安装到现有应用程序中</span></a></h3>
<p>如果你有兴趣在现有的 Laravel 应用程序中使用 Sail，你可以简单地使用 Composer 包管理器安装 Sail。当然，这些步骤假设你的现有本地开发环境允许你安装 Composer 依赖项：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">composer</span> require laravel/sail <span class="token parameter variable">--dev</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>安装了 Sail 后，你可以运行 <code v-pre>sail:install</code> Artisan 命令。这个命令将会将 Sail 的 <code v-pre>docker-compose.yml</code> 文件发布到你的应用程序的根目录，并通过修改你的 <code v-pre>.env</code> 文件，添加所需的环境变量以连接到 Docker 服务：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">php artisan sail:install</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>最后，你可以启动 Sail。要继续学习如何使用 Sail，请继续阅读本文档的其余部分：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">./vendor/bin/sail up</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><blockquote>
<p><strong>注意</strong><br>
如果你使用 Docker Desktop for Linux，你应该通过执行以下命令使用 <code v-pre>default</code> Docker 上下文：<code v-pre>docker context use default</code>。</p>
</blockquote>
<h4 id="添加额外的服务" tabindex="-1"><a class="header-anchor" href="#添加额外的服务"><span>添加额外的服务</span></a></h4>
<p>如果你想要向现有的 Sail 安装中添加额外的服务，你可以运行 <code v-pre>sail:add</code> Artisan 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">php artisan sail:add</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h4 id="使用-devcontainers" tabindex="-1"><a class="header-anchor" href="#使用-devcontainers"><span>使用 Devcontainers</span></a></h4>
<p>如果你想要在 <a href="https://code.visualstudio.com/docs/remote/containers" target="_blank" rel="noopener noreferrer">Devcontainer</a> 中进行开发，你可以向 <code v-pre>sail:install</code> 命令提供 <code v-pre>--devcontainer</code> 选项。<code v-pre>--devcontainer</code> 选项将指示 <code v-pre>sail:install</code> 命令将默认的 <code v-pre>.devcontainer/devcontainer.json</code> 文件发布到你的应用程序的根目录：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">php artisan sail:install <span class="token parameter variable">--devcontainer</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h3 id="重建-sail-镜像" tabindex="-1"><a class="header-anchor" href="#重建-sail-镜像"><span>重建 Sail 镜像</span></a></h3>
<p>有时候你可能想要完全重建你的 Sail 镜像，以确保所有镜像的软件包和软件都是最新的。你可以使用 <code v-pre>build</code> 命令来实现这一点：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">docker</span> compose down <span class="token parameter variable">-v</span></span>
<span class="line"></span>
<span class="line">sail build --no-cache</span>
<span class="line"></span>
<span class="line">sail up</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="配置-shell-别名" tabindex="-1"><a class="header-anchor" href="#配置-shell-别名"><span>配置 Shell 别名</span></a></h3>
<p>默认情况下，Sail 命令是通过所有新的 Laravel 应用程序中包含的 <code v-pre>vendor/bin/sail</code> 脚本来调用的：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">./vendor/bin/sail up</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>然而，与其反复输入 <code v-pre>vendor/bin/sail</code> 来执行 Sail 命令，你可能希望配置一个 shell 别名，这样可以更轻松地执行 Sail 的命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token builtin class-name">alias</span> <span class="token assign-left variable">sail</span><span class="token operator">=</span><span class="token string">'sh $([ -f sail ] &amp;&amp; echo sail || echo vendor/bin/sail)'</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>为了确保这个别名始终可用，你可以将其添加到你的家目录中的 shell 配置文件中，比如 <code v-pre>~/.zshrc</code> 或 <code v-pre>~/.bashrc</code>，然后重新启动你的 shell。</p>
<p>一旦配置了 shell 别名，你可以通过简单地输入 <code v-pre>sail</code> 来执行 Sail 命令。本文档中其余的示例将假定你已经配置了这个别名：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail up</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h2 id="启动和停止-sail" tabindex="-1"><a class="header-anchor" href="#启动和停止-sail"><span>启动和停止 Sail</span></a></h2>
<p>Laravel Sail 的 <code v-pre>docker-compose.yml</code> 文件定义了各种 Docker 容器，这些容器共同协作，帮助你构建 Laravel 应用程序。这些容器中的每一个都是你的 <code v-pre>docker-compose.yml</code> 文件中 <code v-pre>services</code> 配置的一个条目。<code v-pre>laravel.test</code> 容器是主要的应用程序容器，将为你提供应用程序服务。</p>
<p>在启动 Sail 之前，你应该确保你的本地计算机上没有其他的 web 服务器或数据库正在运行。要启动应用程序 <code v-pre>docker-compose.yml</code> 文件中定义的所有 Docker 容器，你应该执行 <code v-pre>up</code> 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail up</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>要在后台启动所有 Docker 容器，你可以以 「detached」 模式启动 Sail：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail up <span class="token parameter variable">-d</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>一旦应用程序的容器已经启动，你可以在 web 浏览器中访问项目：<a href="http://localhost/" target="_blank" rel="noopener noreferrer">localhost</a>。</p>
<p>要停止所有容器，你可以简单地按下 Control + C 来停止容器的执行。或者，如果容器在后台运行，你可以使用 <code v-pre>stop</code> 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail stop</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h2 id="执行命令" tabindex="-1"><a class="header-anchor" href="#执行命令"><span>执行命令</span></a></h2>
<p>在使用 Laravel Sail 时，你的应用程序是在一个 Docker 容器中执行的，并且与你的本地计算机隔离。然而，Sail 提供了一种方便的方式来运行各种命令，比如任意的 PHP 命令、Artisan 命令、Composer 命令以及 Node / NPM 命令。</p>
<p><strong>在阅读 Laravel 文档时，你经常会看到关于 Composer、Artisan 和 Node / NPM 命令的引用，而没有提到 Sail。</strong> 这些示例假设这些工具已经安装在你的本地计算机上。如果你正在使用 Sail 来搭建本地的 Laravel 开发环境，你应该使用 Sail 来执行这些命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token comment"># 在本地运行 Artisan 命令...</span></span>
<span class="line">php artisan queue:work</span>
<span class="line"></span>
<span class="line"><span class="token comment"># 在 Laravel Sail 中运行 Artisan 命令...</span></span>
<span class="line">sail artisan queue:work</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="执行-php-命令" tabindex="-1"><a class="header-anchor" href="#执行-php-命令"><span>执行 PHP 命令</span></a></h3>
<p>可以使用 <code v-pre>php</code> 命令来执行 PHP 命令。当然，这些命令将使用为你的应用程序配置的 PHP 版本来执行。要了解更多关于 Laravel Sail 可用的 PHP 版本，请参考 <a href="#sail-php-versions">PHP 版本文档</a>：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail php <span class="token parameter variable">--version</span></span>
<span class="line"></span>
<span class="line">sail php script.php</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="执行-composer-命令" tabindex="-1"><a class="header-anchor" href="#执行-composer-命令"><span>执行 Composer 命令</span></a></h3>
<p>可以使用 <code v-pre>composer</code> 命令来执行 Composer 命令。Laravel Sail 的应用程序容器包含了 Composer 的安装：</p>
<div class="language-nothing line-numbers-mode" data-highlighter="prismjs" data-ext="nothing" data-title="nothing"><pre v-pre class="language-nothing"><code><span class="line">sail composer require laravel/sanctum</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h4 id="为现有应用程序安装-composer-依赖" tabindex="-1"><a class="header-anchor" href="#为现有应用程序安装-composer-依赖"><span>为现有应用程序安装 Composer 依赖</span></a></h4>
<p>如果你是与团队一起开发应用程序，可能不是最初创建 Laravel 应用程序的人。因此，在将应用程序的存储库克隆到你的本地计算机后，应用程序的 Composer 依赖关系，包括 Sail，在你的计算机上都不会安装。</p>
<p>你可以通过进入应用程序目录并执行以下命令来安装应用程序的依赖关系。该命令使用一个包含 PHP 和 Composer 的小型 Docker 容器来安装应用程序的依赖项：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">docker</span> run <span class="token parameter variable">--rm</span> <span class="token punctuation">\</span></span>
<span class="line">    <span class="token parameter variable">-u</span> <span class="token string">"<span class="token variable"><span class="token variable">$(</span><span class="token function">id</span> <span class="token parameter variable">-u</span><span class="token variable">)</span></span>:<span class="token variable"><span class="token variable">$(</span><span class="token function">id</span> <span class="token parameter variable">-g</span><span class="token variable">)</span></span>"</span> <span class="token punctuation">\</span></span>
<span class="line">    <span class="token parameter variable">-v</span> <span class="token string">"<span class="token variable"><span class="token variable">$(</span><span class="token builtin class-name">pwd</span><span class="token variable">)</span></span>:/var/www/html"</span> <span class="token punctuation">\</span></span>
<span class="line">    <span class="token parameter variable">-w</span> /var/www/html <span class="token punctuation">\</span></span>
<span class="line">    laravelsail/php83-composer:latest <span class="token punctuation">\</span></span>
<span class="line">    <span class="token function">composer</span> <span class="token function">install</span> --ignore-platform-reqs</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>在使用 <code v-pre>laravelsail/phpXX-composer</code> 镜像时，你应该使用与你计划在应用程序中使用的 PHP 版本相同的版本（<code v-pre>80</code>、<code v-pre>81</code>、<code v-pre>82</code> 或 <code v-pre>83</code>）。</p>
<h3 id="执行-artisan-命令" tabindex="-1"><a class="header-anchor" href="#执行-artisan-命令"><span>执行 Artisan 命令</span></a></h3>
<p>可以使用 <code v-pre>artisan</code> 命令来执行 Laravel Artisan 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail artisan queue:work</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h3 id="执行-node-npm-命令" tabindex="-1"><a class="header-anchor" href="#执行-node-npm-命令"><span>执行 Node / NPM 命令</span></a></h3>
<p>可以使用 <code v-pre>node</code> 命令来执行 Node 命令，而使用 <code v-pre>npm</code> 命令来执行 NPM 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail <span class="token function">node</span> <span class="token parameter variable">--version</span></span>
<span class="line"></span>
<span class="line">sail <span class="token function">npm</span> run dev</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>如果你希望，也可以使用 Yarn 而不是 NPM：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail <span class="token function">yarn</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h2 id="与数据库交互" tabindex="-1"><a class="header-anchor" href="#与数据库交互"><span>与数据库交互</span></a></h2>
<h3 id="mysql" tabindex="-1"><a class="header-anchor" href="#mysql"><span>MySQL</span></a></h3>
<p>你可能已经注意到，你的应用程序的 <code v-pre>docker-compose.yml</code> 文件中包含了一个 MySQL 容器的条目。这个容器使用了一个 <a href="https://docs.docker.com/storage/volumes/" target="_blank" rel="noopener noreferrer">Docker 卷</a>，这样即使停止和重新启动容器，数据库中存储的数据也会被保留。</p>
<p>此外，当 MySQL 容器第一次启动时，它会为你创建两个数据库。第一个数据库的名称使用你的 <code v-pre>DB_DATABASE</code> 环境变量的值，并用于你的本地开发。第二个是一个专用的测试数据库，名称为 <code v-pre>testing</code>，将确保你的测试不会干扰你的开发数据。</p>
<p>一旦启动了你的容器，你可以通过将应用程序的 <code v-pre>.env</code> 文件中的 <code v-pre>DB_HOST</code> 环境变量设置为 <code v-pre>mysql</code> 来连接到应用程序内部的 MySQL 实例。</p>
<p>要从本地计算机连接到应用程序的 MySQL 数据库，你可以使用诸如 <a href="https://tableplus.com/" target="_blank" rel="noopener noreferrer">TablePlus</a> 之类的图形化数据库管理应用程序。默认情况下，MySQL 数据库可以在 <code v-pre>localhost</code> 的 3306 端口访问，访问凭据对应于你的 <code v-pre>DB_USERNAME</code> 和 <code v-pre>DB_PASSWORD</code> 环境变量的值。或者，你可以作为 <code v-pre>root</code> 用户连接，这也会使用你的 <code v-pre>DB_PASSWORD</code> 环境变量的值作为密码。</p>
<h3 id="redis" tabindex="-1"><a class="header-anchor" href="#redis"><span>Redis</span></a></h3>
<p>你的应用程序的 <code v-pre>docker-compose.yml</code> 文件还包含了一个 <a href="https://redis.io/" target="_blank" rel="noopener noreferrer">Redis</a> 容器的条目。这个容器使用了一个 <a href="https://docs.docker.com/storage/volumes/" target="_blank" rel="noopener noreferrer">Docker 卷</a>，这样即使停止和重新启动容器，Redis 数据中存储的数据也会被保留。一旦启动了你的容器，你可以通过将应用程序的 <code v-pre>.env</code> 文件中的 <code v-pre>REDIS_HOST</code> 环境变量设置为 <code v-pre>redis</code> 来连接到应用程序内部的 Redis 实例。</p>
<p>要从本地计算机连接到应用程序的 Redis 数据库，你可以使用诸如 <a href="https://tableplus.com/" target="_blank" rel="noopener noreferrer">TablePlus</a> 之类的图形化数据库管理应用程序。默认情况下，Redis 数据库可以在 <code v-pre>localhost</code> 的 6379 端口访问。</p>
<h3 id="meilisearch" tabindex="-1"><a class="header-anchor" href="#meilisearch"><span>Meilisearch</span></a></h3>
<p>如果在安装 Sail 时选择安装 <a href="https://www.meilisearch.com/" target="_blank" rel="noopener noreferrer">Meilisearch</a> 服务，你的应用程序的 <code v-pre>docker-compose.yml</code> 文件将包含一个条目，用于这个与 <a href="https://learnku.com/docs/laravel/11.x/scout" target="_blank" rel="noopener noreferrer">Laravel Scout</a> 集成的强大搜索引擎。一旦启动了你的容器，你可以通过将应用程序的 <code v-pre>MEILISEARCH_HOST</code> 环境变量设置为 <code v-pre>http://meilisearch:7700</code> 来连接到应用程序内部的 Meilisearch 实例。</p>
<p>从你的本地计算机，你可以通过在 Web 浏览器中导航到 <code v-pre>http://localhost:7700</code> 来访问 Meilisearch 的基于 Web 的管理面板。</p>
<h3 id="typesense" tabindex="-1"><a class="header-anchor" href="#typesense"><span>Typesense</span></a></h3>
<p>如果在安装 Sail 时选择安装 <a href="https://typesense.org/" target="_blank" rel="noopener noreferrer">Typesense</a> 服务，你的应用程序的 <code v-pre>docker-compose.yml</code> 文件将包含一个条目，用于这个与 <a href="https://learnku.com/docs/laravel/11.x/scout#typesense" target="_blank" rel="noopener noreferrer">Laravel Scout</a> 原生集成的高速开源搜索引擎。一旦启动了你的容器，你可以通过设置以下环境变量来连接到应用程序内部的 Typesense 实例：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line"><span class="token key attr-name">TYPESENSE_HOST</span><span class="token punctuation">=</span><span class="token value attr-value">typesense</span></span>
<span class="line"><span class="token key attr-name">TYPESENSE_PORT</span><span class="token punctuation">=</span><span class="token value attr-value">8108</span></span>
<span class="line"><span class="token key attr-name">TYPESENSE_PROTOCOL</span><span class="token punctuation">=</span><span class="token value attr-value">http</span></span>
<span class="line"><span class="token key attr-name">TYPESENSE_API_KEY</span><span class="token punctuation">=</span><span class="token value attr-value">xyz</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>从你的本地计算机，你可以通过 <code v-pre>http://localhost:8108</code> 访问 Typesense 的 API。</p>
<h2 id="文件存储" tabindex="-1"><a class="header-anchor" href="#文件存储"><span>文件存储</span></a></h2>
<p>如果在生产环境中运行应用程序时计划使用 Amazon S3 存储文件，你可能希望在安装 Sail 时安装 <a href="https://min.io/" target="_blank" rel="noopener noreferrer">MinIO</a> 服务。MinIO 提供了一个与 S3 兼容的 API，你可以在本地开发中使用 Laravel 的 <code v-pre>s3</code> 文件存储驱动，而无需在生产 S3 环境中创建“测试”存储桶。如果选择在安装 Sail 时安装 MinIO，将会在你的应用程序的 <code v-pre>docker-compose.yml</code> 文件中添加一个 MinIO 配置部分。</p>
<p>默认情况下，你的应用程序的 <code v-pre>filesystems</code> 配置文件已经包含了一个用于 <code v-pre>s3</code> 磁盘的配置。除了用于与 Amazon S3 交互外，你还可以使用它与任何兼容 S3 的文件存储服务进行交互，比如 MinIO，只需简单地修改控制其配置的相关环境变量。例如，当使用 MinIO 时，你的文件系统环境变量配置应定义如下：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line"><span class="token key attr-name">FILESYSTEM_DISK</span><span class="token punctuation">=</span><span class="token value attr-value">s3</span></span>
<span class="line"><span class="token key attr-name">AWS_ACCESS_KEY_ID</span><span class="token punctuation">=</span><span class="token value attr-value">sail</span></span>
<span class="line"><span class="token key attr-name">AWS_SECRET_ACCESS_KEY</span><span class="token punctuation">=</span><span class="token value attr-value">password</span></span>
<span class="line"><span class="token key attr-name">AWS_DEFAULT_REGION</span><span class="token punctuation">=</span><span class="token value attr-value">us-east-1</span></span>
<span class="line"><span class="token key attr-name">AWS_BUCKET</span><span class="token punctuation">=</span><span class="token value attr-value">local</span></span>
<span class="line"><span class="token key attr-name">AWS_ENDPOINT</span><span class="token punctuation">=</span><span class="token value attr-value">http://minio:9000</span></span>
<span class="line"><span class="token key attr-name">AWS_USE_PATH_STYLE_ENDPOINT</span><span class="token punctuation">=</span><span class="token value attr-value">true</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>为了让 Laravel 的 Flysystem 集成在使用 MinIO 时生成正确的 URL，你应该定义 <code v-pre>AWS_URL</code> 环境变量，使其与应用程序的本地 URL 匹配，并在 URL 路径中包含存储桶名称：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line"><span class="token key attr-name">AWS_URL</span><span class="token punctuation">=</span><span class="token value attr-value">http://localhost:9000/local</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>你可以通过 MinIO 控制台创建存储桶，控制台地址为 <code v-pre>http://localhost:8900</code>。MinIO 控制台的默认用户名为 <code v-pre>sail</code>，默认密码为 <code v-pre>password</code>。</p>
<blockquote>
<p><strong>注意</strong><br>
当使用 MinIO 时，通过 <code v-pre>temporaryUrl</code> 方法生成临时存储 URL 不受支持。</p>
</blockquote>
<h2 id="运行测试" tabindex="-1"><a class="header-anchor" href="#运行测试"><span>运行测试</span></a></h2>
<p>Laravel 提供了出色的测试支持，并且你可以使用 Sail 的 <code v-pre>test</code> 命令来运行你的应用程序的 <a href="https://learnku.com/docs/laravel/11.x/testing" target="_blank" rel="noopener noreferrer">功能和单元测试</a>。任何 Pest / PHPUnit 接受的 CLI 选项也可以传递给 <code v-pre>test</code> 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail <span class="token builtin class-name">test</span></span>
<span class="line"></span>
<span class="line">sail <span class="token builtin class-name">test</span> <span class="token parameter variable">--group</span> orders</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>Sail 的 <code v-pre>test</code> 命令等同于运行 <code v-pre>test</code> Artisan 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail artisan <span class="token builtin class-name">test</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>默认情况下，Sail 将创建一个专用的 <code v-pre>testing</code> 数据库，以确保你的测试不会影响到数据库的当前状态。在默认的 Laravel 安装中，Sail 还会配置你的 <code v-pre>phpunit.xml</code> 文件，以在执行测试时使用这个数据库：</p>
<div class="language-xml line-numbers-mode" data-highlighter="prismjs" data-ext="xml" data-title="xml"><pre v-pre class="language-xml"><code><span class="line"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>env</span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>DB_DATABASE<span class="token punctuation">"</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>testing<span class="token punctuation">"</span></span><span class="token punctuation">/></span></span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h3 id="laravel-dusk" tabindex="-1"><a class="header-anchor" href="#laravel-dusk"><span>Laravel Dusk</span></a></h3>
<p><a href="https://learnku.com/docs/laravel/11.x/dusk" target="_blank" rel="noopener noreferrer">Laravel Dusk</a> 提供了一套表达力强、易于使用的浏览器自动化和测试 API。借助 Sail，你可以在本地计算机上运行这些测试，而无需安装 Selenium 或其他工具。要开始使用，取消注释应用程序的 <code v-pre>docker-compose.yml</code> 文件中的 Selenium 服务：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line">selenium:</span>
<span class="line">    image: 'selenium/standalone-chrome'</span>
<span class="line">    extra_hosts:</span>
<span class="line">      - 'host.docker.internal:host-gateway'</span>
<span class="line">    volumes:</span>
<span class="line">        - '/dev/shm:/dev/shm'</span>
<span class="line">    networks:</span>
<span class="line">        - sail</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>接下来，确保应用程序的 <code v-pre>docker-compose.yml</code> 文件中的 <code v-pre>laravel.test</code> 服务有一个 <code v-pre>depends_on</code> 条目指向 <code v-pre>selenium</code>：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line">depends_on:</span>
<span class="line">    - mysql</span>
<span class="line">    - redis</span>
<span class="line">    - selenium</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>最后，你可以通过启动 Sail 并运行 <code v-pre>dusk</code> 命令来运行你的 Dusk 测试套件：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail dusk</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h4 id="apple-silicon-上的-selenium" tabindex="-1"><a class="header-anchor" href="#apple-silicon-上的-selenium"><span>Apple Silicon 上的 Selenium</span></a></h4>
<p>如果你的本地计算机使用的是 Apple Silicon 芯片，你的 <code v-pre>selenium</code> 服务必须使用 <code v-pre>seleniarm/standalone-chromium</code> 镜像：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line">selenium:</span>
<span class="line">    image: 'seleniarm/standalone-chromium'</span>
<span class="line">    extra_hosts:</span>
<span class="line">        - 'host.docker.internal:host-gateway'</span>
<span class="line">    volumes:</span>
<span class="line">        - '/dev/shm:/dev/shm'</span>
<span class="line">    networks:</span>
<span class="line">        - sail</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="预览电子邮件" tabindex="-1"><a class="header-anchor" href="#预览电子邮件"><span>预览电子邮件</span></a></h2>
<p>Laravel Sail 的默认 <code v-pre>docker-compose.yml</code> 文件包含一个用于 <a href="https://github.com/axllent/mailpit" target="_blank" rel="noopener noreferrer">Mailpit</a> 的服务条目。Mailpit 在本地开发期间拦截应用程序发送的电子邮件，并提供一个方便的 Web 界面，让你可以在浏览器中预览你的电子邮件消息。在使用 Sail 时，Mailpit 的默认主机是 <code v-pre>mailpit</code>，可通过端口 1025 访问：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line"><span class="token key attr-name">MAIL_HOST</span><span class="token punctuation">=</span><span class="token value attr-value">mailpit</span></span>
<span class="line"><span class="token key attr-name">MAIL_PORT</span><span class="token punctuation">=</span><span class="token value attr-value">1025</span></span>
<span class="line"><span class="token key attr-name">MAIL_ENCRYPTION</span><span class="token punctuation">=</span><span class="token value attr-value">null</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>当 Sail 在运行时，你可以通过以下链接访问 Mailpit 网页界面：<a href="http://localhost:8025/" target="_blank" rel="noopener noreferrer">localhost:8025</a></p>
<h2 id="容器-cli" tabindex="-1"><a class="header-anchor" href="#容器-cli"><span>容器 CLI</span></a></h2>
<p>有时候你可能希望在应用程序的容器内启动一个 Bash 会话。你可以使用 <code v-pre>shell</code> 命令连接到应用程序的容器，这样你就可以检查其文件和安装的服务，以及在容器内执行任意的 shell 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail shell</span>
<span class="line"></span>
<span class="line">sail root-shell</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>要启动一个新的 <a href="https://github.com/laravel/tinker" target="_blank" rel="noopener noreferrer">Laravel Tinker</a> 会话，你可以执行 <code v-pre>tinker</code> 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail tinker</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h2 id="php-版本" tabindex="-1"><a class="header-anchor" href="#php-版本"><span>PHP 版本</span></a></h2>
<p>Sail 目前支持通过 PHP 8.3、8.2、8.1 或 PHP 8.0 提供应用程序服务。Sail 当前使用的默认 PHP 版本是 PHP 8.3。要更改用于提供应用程序服务的 PHP 版本，你应该更新应用程序的 <code v-pre>docker-compose.yml</code> 文件中 <code v-pre>laravel.test</code> 容器的 <code v-pre>build</code> 定义：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line"><span class="token comment"># PHP 8.3</span></span>
<span class="line">context: ./vendor/laravel/sail/runtimes/8.3</span>
<span class="line"></span>
<span class="line"><span class="token comment"># PHP 8.2</span></span>
<span class="line">context: ./vendor/laravel/sail/runtimes/8.2</span>
<span class="line"></span>
<span class="line"><span class="token comment"># PHP 8.1</span></span>
<span class="line">context: ./vendor/laravel/sail/runtimes/8.1</span>
<span class="line"></span>
<span class="line"><span class="token comment"># PHP 8.0</span></span>
<span class="line">context: ./vendor/laravel/sail/runtimes/8.0</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>此外，你可能希望更新你的 <code v-pre>image</code> 名称以反映你的应用程序使用的 PHP 版本。此选项也在应用程序的 <code v-pre>docker-compose.yml</code> 文件中定义：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line">image: sail-8.2/app</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>更新应用程序的 <code v-pre>docker-compose.yml</code> 文件后，你应该重建容器镜像：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail build --no-cache</span>
<span class="line"></span>
<span class="line">sail up</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="node-版本" tabindex="-1"><a class="header-anchor" href="#node-版本"><span>Node 版本</span></a></h2>
<p>Sail 默认安装 Node 20。要更改构建镜像时安装的 Node 版本，你可以更新应用程序的 <code v-pre>docker-compose.yml</code> 文件中 <code v-pre>laravel.test</code> 服务的 <code v-pre>build.args</code> 定义：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line">build:</span>
<span class="line">    args:</span>
<span class="line">        WWWGROUP: '${WWWGROUP}'</span>
<span class="line">        NODE_VERSION: '18'</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>更新应用程序的 <code v-pre>docker-compose.yml</code> 文件后，你应该重建容器镜像：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail build --no-cache</span>
<span class="line"></span>
<span class="line">sail up</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="分享你的网站" tabindex="-1"><a class="header-anchor" href="#分享你的网站"><span>分享你的网站</span></a></h2>
<p>有时候你可能需要公开分享你的网站，以便为同事预览你的网站或测试应用程序的 Webhook 集成。要分享你的网站，你可以使用 <code v-pre>share</code> 命令。执行此命令后，你将获得一个随机的 <code v-pre>laravel-sail.site</code> URL，你可以用它来访问你的应用程序：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail share</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>在通过 <code v-pre>share</code> 命令分享你的网站时，你应该在应用程序的 <code v-pre>bootstrap/app.php</code> 文件中使用 <code v-pre>trustProxies</code> 中间件方法配置应用程序的受信任代理。否则，诸如 <code v-pre>url</code> 和 <code v-pre>route</code> 这样的 URL 生成辅助程序将无法确定在 URL 生成期间应该使用的正确 HTTP 主机：</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token operator">-></span><span class="token function">withMiddleware</span><span class="token punctuation">(</span><span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token class-name type-declaration">Middleware</span> <span class="token variable">$middleware</span><span class="token punctuation">)</span> <span class="token punctuation">{</span></span>
<span class="line">    <span class="token variable">$middleware</span><span class="token operator">-></span><span class="token function">trustProxies</span><span class="token punctuation">(</span><span class="token argument-name">at</span><span class="token punctuation">:</span> <span class="token punctuation">[</span></span>
<span class="line">        <span class="token string single-quoted-string">'*'</span><span class="token punctuation">,</span></span>
<span class="line">    <span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"><span class="token punctuation">}</span><span class="token punctuation">)</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>如果你想为你的共享网站选择子域名，你可以在执行 <code v-pre>share</code> 命令时提供 <code v-pre>subdomain</code> 选项：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail share <span class="token parameter variable">--subdomain</span><span class="token operator">=</span>my-sail-site</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><blockquote>
<p><strong>注意</strong><br>
<code v-pre>share</code> 命令由 <a href="https://beyondco.de/" target="_blank" rel="noopener noreferrer">BeyondCode</a> 开发的开源隧道服务 <a href="https://github.com/beyondcode/expose" target="_blank" rel="noopener noreferrer">Expose</a> 提供支持。</p>
</blockquote>
<h2 id="使用-xdebug-进行调试" tabindex="-1"><a class="header-anchor" href="#使用-xdebug-进行调试"><span>使用 Xdebug 进行调试</span></a></h2>
<p>Laravel Sail 的 Docker 配置包含对 <a href="https://xdebug.org/" target="_blank" rel="noopener noreferrer">Xdebug</a> 的支持，这是 PHP 的一款流行且强大的调试器。为了启用 Xdebug，你需要在应用程序的 <code v-pre>.env</code> 文件中添加一些变量来<a href="https://xdebug.org/docs/step_debug#mode" target="_blank" rel="noopener noreferrer">配置 Xdebug</a>。在启动 Sail 之前，你必须设置适当的模式来启用 Xdebug：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line"><span class="token key attr-name">SAIL_XDEBUG_MODE</span><span class="token punctuation">=</span><span class="token value attr-value">develop,debug,coverage</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h4 id="linux-主机-ip-配置" tabindex="-1"><a class="header-anchor" href="#linux-主机-ip-配置"><span>Linux 主机 IP 配置</span></a></h4>
<p>在内部，<code v-pre>XDEBUG_CONFIG</code> 环境变量被定义为 <code v-pre>client_host=host.docker.internal</code>，以便为 Mac 和 Windows (WSL2) 正确配置 Xdebug。如果你的本地计算机运行的是 Linux，你应该确保你正在运行 Docker Engine 17.06.0+ 和 Compose 1.16.0+。否则，你将需要手动定义这个环境变量，如下所示。</p>
<p>首先，你应该通过运行以下命令确定要添加到环境变量的正确主机 IP 地址。通常，<code v-pre>&lt;container-name&gt;</code> 应该是为你的应用程序提供服务的容器的名称，通常以 <code v-pre>_laravel.test_1</code> 结尾：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token function">docker</span> inspect <span class="token parameter variable">-f</span> <span class="token punctuation">{</span><span class="token punctuation">{</span>range.NetworkSettings.Networks<span class="token punctuation">}</span><span class="token punctuation">}</span><span class="token punctuation">{</span><span class="token punctuation">{</span>.Gateway<span class="token punctuation">}</span><span class="token punctuation">}</span><span class="token punctuation">{</span><span class="token punctuation">{</span>end<span class="token punctuation">}</span><span class="token punctuation">}</span> <span class="token operator">&lt;</span>container-name<span class="token operator">></span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>获得正确的主机 IP 地址后，你应该在应用程序的 <code v-pre>.env</code> 文件中定义 <code v-pre>SAIL_XDEBUG_CONFIG</code> 变量：</p>
<div class="language-ini line-numbers-mode" data-highlighter="prismjs" data-ext="ini" data-title="ini"><pre v-pre class="language-ini"><code><span class="line"><span class="token key attr-name">SAIL_XDEBUG_CONFIG</span><span class="token punctuation">=</span><span class="token value attr-value">"<span class="token inner-value">client_host=&lt;host-ip-address></span>"</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><h3 id="xdebug-cli-使用" tabindex="-1"><a class="header-anchor" href="#xdebug-cli-使用"><span>Xdebug CLI 使用</span></a></h3>
<p>可以使用 <code v-pre>sail debug</code> 命令在运行 Artisan 命令时启动调试会话：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line"><span class="token comment"># 不使用 Xdebug 运行 Artisan 命令...</span></span>
<span class="line">sail artisan migrate</span>
<span class="line"></span>
<span class="line"><span class="token comment"># 使用 Xdebug 运行 Artisan 命令...</span></span>
<span class="line">sail debug migrate</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="xdebug-浏览器使用" tabindex="-1"><a class="header-anchor" href="#xdebug-浏览器使用"><span>Xdebug 浏览器使用</span></a></h3>
<p>在通过 Web 浏览器与应用程序交互时调试应用程序，请按照 Xdebug 提供的 <a href="https://xdebug.org/docs/step_debug#web-application" target="_blank" rel="noopener noreferrer">说明</a> 来启动一个来自 Web 浏览器的 Xdebug 会话。</p>
<p>如果你使用 PhpStorm，请查阅 JetBrains 的关于 <a href="https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html" target="_blank" rel="noopener noreferrer">零配置调试</a> 的文档。</p>
<blockquote>
<p><strong>警告</strong><br>
Laravel Sail 依赖于 <code v-pre>artisan serve</code> 来提供应用程序服务。<code v-pre>artisan serve</code> 命令仅在 Laravel 版本 8.53.0 中接受 <code v-pre>XDEBUG_CONFIG</code> 和 <code v-pre>XDEBUG_MODE</code> 变量。较旧版本的 Laravel（8.52.0 及以下）不支持这些变量，并且不会接受调试连接。</p>
</blockquote>
<h2 id="自定义" tabindex="-1"><a class="header-anchor" href="#自定义"><span>自定义</span></a></h2>
<p>由于 Sail 只是 Docker，你可以自由地定制几乎关于它的一切。要发布 Sail 自己的 Dockerfile，你可以执行 <code v-pre>sail:publish</code> 命令：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail artisan sail:publish</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>运行此命令后，Laravel Sail 使用的 Dockerfile 和其他配置文件将被放置在应用程序根目录下的 <code v-pre>docker</code> 目录中。在自定义 Sail 安装后，你可能希望在应用程序的 <code v-pre>docker-compose.yml</code> 文件中为应用程序容器更改镜像名称。这样做后，使用 <code v-pre>build</code> 命令重新构建应用程序的容器。如果你在单台计算机上使用 Sail 开发多个 Laravel 应用程序，为应用程序镜像分配一个唯一的名称尤为重要：</p>
<div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre v-pre class="language-bash"><code><span class="line">sail build --no-cache</span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><blockquote>
<p>本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接<br>
我们的翻译工作遵照 <a href="https://learnku.com/docs/guide/cc4.0/6589" target="_blank" rel="noopener noreferrer">CC 协议</a>，如果我们的工作有侵犯到您的权益，请及时联系我们。</p>
</blockquote>
<hr>
<blockquote>
<p>原文地址：<a href="https://learnku.com/docs/laravel/11.x/sailmd/16731" target="_blank" rel="noopener noreferrer">https://learnku.com/docs/laravel/11.x/sa...</a></p>
<p>译文地址：<a href="https://learnku.com/docs/laravel/11.x/sailmd/16731" target="_blank" rel="noopener noreferrer">https://learnku.com/docs/laravel/11.x/sa...</a></p>
</blockquote>
</div></template>


